Rework docs structure#2308
Conversation
| theme: | ||
| name: 'material' | ||
| features: | ||
| - navigation.sections |
There was a problem hiding this comment.
- What change does this feature effect?
- Where would I find this documented?
There was a problem hiding this comment.
This allows showing navigation sections as always-unfolded, instead of foldable groupings as is the default in mkdocs.
This is here: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections
There was a problem hiding this comment.
Is this clarification enough or are there any changes to the code you'd think worthy?
lovelydinosaur
left a comment
lovelydinosaur
left a comment
There was a problem hiding this comment.
The section changing is very pleasing on the eye. Certainly an aid to my mental navigation.
Moving that part of the exceptions docs also made much sense to me.
One inline comment which could be addressed. Not strictly a blocker.
Nicely chosen changes, Florimond. 🙏🏼
florimondmanca
force-pushed
the
fm/docs-structure
branch
from
c91ea74 to
d95df67
Compare
florimondmanca
force-pushed
the
fm/docs-structure
branch
from
d95df67 to
7d6d989
Compare
|
Let’s merge then! :-) |
3 participants
I didn't raise a discussion about this, but this PR also serves as a hands-on proposal. Happy to discuss separately if need be.
This PR restructures the documentation in four well-visible sections:
Open for text version
This takes inspiration from the 4-part Tutorials/How-To's/Discussions/Reference theorised by Daniele Procida (see What nobody tells you about documentation (talk)).
It doesn't exactly match that structure -- e.g. I don't think we've got something resembling "discussions" yet, although stuff like #207 would be potential candidates.
But we do have different kinds of documentation in HTTPX already. The motivation here was to group them to help people find what they're looking for more easily.
So, each section answers the following questions:
The only shuffling of content I had to do was split the "Exceptions" docs across Quickstart vs. API Reference, as it mixed general usage hints and reference material. This matches how there's a Exceptions and errors section in the Requests quickstart documentation, and then an Exceptions section on its API Reference page.